<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.9.1"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>FLAC: FLAC/metadata.h: metadata interfaces</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectalign" style="padding-left: 0.5em;">
   <div id="projectname">FLAC
   &#160;<span id="projectnumber">1.4.3</span>
   </div>
   <div id="projectbrief">Free Lossless Audio Codec</div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.1 -->
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
$(function() {
  initMenu('',false,false,'search.php','Search');
});
/* @license-end */</script>
<div id="main-nav"></div>
</div><!-- top -->
<div class="header">
  <div class="summary">
<a href="#groups">Modules</a>  </div>
  <div class="headertitle">
<div class="title">FLAC/metadata.h: metadata interfaces<div class="ingroups"><a class="el" href="group__flac.html">FLAC C API</a></div></div>  </div>
</div><!--header-->
<div class="contents">
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="groups"></a>
Modules</h2></td></tr>
<tr class="memitem:group__flac__metadata__level0"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__flac__metadata__level0.html">FLAC/metadata.h: metadata level 0 interface</a></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table>
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
<p>This module provides functions for creating and manipulating FLAC metadata blocks in memory, and three progressively more powerful interfaces for traversing and editing metadata in native FLAC files. Note that currently only the Chain interface (level 2) supports Ogg FLAC files, and it is read-only i.e. no writing back changed metadata to file. </p>
<p>There are three metadata interfaces of increasing complexity:</p>
<p>Level 0: Read-only access to the STREAMINFO, VORBIS_COMMENT, CUESHEET, and PICTURE blocks.</p>
<p>Level 1: Read-write access to all metadata blocks. This level is write- efficient in most cases (more on this below), and uses less memory than level 2.</p>
<p>Level 2: Read-write access to all metadata blocks. This level is write- efficient in all cases, but uses more memory since all metadata for the whole file is read into memory and manipulated before writing out again.</p>
<p>What do we mean by efficient? Since FLAC metadata appears at the beginning of the file, when writing metadata back to a FLAC file it is possible to grow or shrink the metadata such that the entire file must be rewritten. However, if the size remains the same during changes or PADDING blocks are utilized, only the metadata needs to be overwritten, which is much faster.</p>
<p>Efficient means the whole file is rewritten at most one time, and only when necessary. Level 1 is not efficient only in the case that you cause more than one metadata block to grow or shrink beyond what can be accommodated by padding. In this case you should probably use level 2, which allows you to edit all the metadata for a file in memory and write it out all at once.</p>
<p>All levels know how to skip over and not disturb an ID3v2 tag at the front of the file.</p>
<p>All levels access files via their filenames. In addition, level 2 has additional alternative read and write functions that take an I/O handle and callbacks, for situations where access by filename is not possible.</p>
<p>In addition to the three interfaces, this module defines functions for creating and manipulating various metadata objects in memory. As we see from the Format module, FLAC metadata blocks in memory are very primitive structures for storing information in an efficient way. Reading information from the structures is easy but creating or modifying them directly is more complex. The metadata object routines here facilitate this by taking care of the consistency and memory management drudgery.</p>
<p>Unless you will be using the level 1 or 2 interfaces to modify existing metadata however, you will not probably not need these.</p>
<p>From a dependency standpoint, none of the encoders or decoders require the metadata module. This is so that embedded users can strip out the metadata module from libFLAC to reduce the size and complexity. </p>
</div><!-- contents -->

<hr size="1"/>
Copyright (c) 2000-2009  Josh Coalson
Copyright (c) 2011-2023  Xiph.Org Foundation
<!-- Copyright (c) 2000-2009  Josh Coalson -->
<!-- Copyright (c) 2011-2023  Xiph.Org Foundation -->
<!-- Permission is granted to copy, distribute and/or modify this document -->
<!-- under the terms of the GNU Free Documentation License, Version 1.1 -->
<!-- or any later version published by the Free Software Foundation; -->
<!-- with no invariant sections. -->
<!-- A copy of the license can be found at http://www.gnu.org/copyleft/fdl.html -->
</body>
</html>
